

    \filetitle{dbbatch}{Run a batch job to create new database fields}{dbase/dbbatch}

	\paragraph{Syntax}

\begin{verbatim}
[D,Processed,Added] = dbbatch(D,NewName,Expr,...)
\end{verbatim}

\paragraph{Input arguments}

\begin{itemize}
\item
  \texttt{D} {[} struct {]} - Input database.
\item
  \texttt{NewName} {[} char {]} - Pattern that will be used to create
  names for new database fields based on the existing ones; use
  \texttt{\textquotesingle{}\$0\textquotesingle{}} to refer to the name
  of the currently processed database field; use
  \texttt{\textquotesingle{}\$1\textquotesingle{}},
  \texttt{\textquotesingle{}\$2\textquotesingle{}}, etc. to refer to
  tokens captured in regular expression specified in the
  \texttt{\textquotesingle{}namefilter=\textquotesingle{}} option.
\item
  \texttt{Expr} {[} char {]} - Expression that will be evaluated on a
  selection of existing database entries to create new database entries;
  the expression can include
  \texttt{\textquotesingle{}\$0\textquotesingle{}},
  \texttt{\textquotesingle{}\$1\textquotesingle{}}, etc.
\end{itemize}

\paragraph{Output arguments}

\begin{itemize}
\item
  \texttt{D} {[} struct {]} - Output database.
\item
  \texttt{Processed} {[} cellstr {]} - List of database fields that have
  been used to create new fields.
\item
  \texttt{Added} {[} cellstr {]} - List of new database fields created
  by evaluating \texttt{Expr} on the corresponding field in
  \texttt{Processed}.
\end{itemize}

\paragraph{Options}

\begin{itemize}
\item
  \texttt{\textquotesingle{}classFilter=\textquotesingle{}} {[} char
  \textbar{} \emph{\texttt{Inf}} {]} - From the existing database
  entries, select only those that are objects of the specified class or
  classes, and evaluate the expression \texttt{Expr} on these.
\item
  \texttt{\textquotesingle{}fresh=\textquotesingle{}} {[} \texttt{true}
  \textbar{} \emph{\texttt{false}} {]} - If \texttt{true}, the output
  database will only contain the newly created entries; if
  \texttt{false} the output database will also include all the entries
  from the input database.
\item
  \texttt{\textquotesingle{}nameFilter=\textquotesingle{}} {[} char
  \textbar{} \emph{empty} {]} - From the existing database entries,
  select only those that match this regular expression, and evaluate the
  expression \texttt{Expr} on these.
\item
  \texttt{\textquotesingle{}nameList=\textquotesingle{}} {[} cellstr
  \textbar{} \emph{\texttt{Inf}} {]} - Evaluate the \texttt{COMMAND} on
  this list of existing database entries.
\item
  \texttt{\textquotesingle{}stringList=\textquotesingle{}} {[} cellstr
  \textbar{} \emph{empty} {]} - Evaluate the expression \texttt{Expr} on
  this list of strings; the strings do not need to be names existing in
  the database; this options can be comined with
  \texttt{\textquotesingle{}nameFilter=\textquotesingle{}},
  \texttt{\textquotesingle{}nameList=\textquotesingle{}}, and/or
  \texttt{\textquotesingle{}classFilter=\textquotesingle{}} to narrow
  the selection.
\end{itemize}

\paragraph{Description}

This function is primarily meant to create new database fields, each
based on an existing one. If you, on the otherhand, only wish to modify
a number of existing fields without adding any new ones, use
\href{dbase/dbfun}{\texttt{dbfun}} instead.

The expression \texttt{Expr} is evaluated in the caller workspace, and
hence may refer to any variables existing in the workspace, not only to
the database and its fields.

To convert the strings \texttt{\$0}, \texttt{\$1}, \texttt{\$2}, etc. to
lower case or upper case, use the dot or colon syntax: \texttt{\$.0},
\texttt{\$.1}, \texttt{\$.2} for ower case, and \texttt{\$:0},
\texttt{\$:1}, \texttt{\$:2} for upper case.

\subparagraph{Failure}

The function \texttt{dbbatch} will \emph{always} fail when called on a
sub-database from within a function (as opposed to a script). A
sub-database is a struct within a struct, a struct within a cell array,
a struct within an array of structs, etc.

\begin{verbatim}
function ...
    d.e = dbbatch(d.e,...);
    ...
end

function ...
    d{1} = dbbatch(d{1},...);
    ...
end

function ...
    d(1) = dbbatch(d(1),...);
    ...
end
\end{verbatim}

\paragraph{Example}

For each field (all assumed to be tseries) create a first difference,
and name the new series \texttt{DX} where \texttt{X} is the name of the
original series.

\begin{verbatim}
d = dbbatch(d,'D$0','diff(d.$0)');
\end{verbatim}

Note that the original series will be presered in the database, together
with the newly created ones.

\paragraph{Example}

Suppose that in database \texttt{D} you want to seasonally adjust all
time series whose names end with \texttt{\_u}, and give these seasonally
adjusted series names without the \_u.

\begin{verbatim}
d = dbbatch(d,'$1','x12(d.$0)','nameFilter','(.*)u');
\end{verbatim}

or, if you want to make sure only tseries objects will be selected (in
case there are database entries ending with a \texttt{u} other than
tseries objects)

\begin{verbatim}
d = dbbatch(d,'$1','x12(d.$0)', ...
    'nameFilter=','(.*)u','classFilter=','tseries');
\end{verbatim}


